Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager

Summary of the Image Compression Manager

C Summary

Constants

/* determines if Image Compression Manager is available */
#define gestaltCompressionMgr 'icmp'

/* smallest data buffer you may allocate for image data spooling */
#define codecMinimumDataSize 32768

/* compressor component type */
#define compressorComponentType 'imco'
/* decompressor component type */
#define decompressorComponentType 'imdc'

/* Image Compression Manager function control flags */
#define codecFlagUseImageBuffer (1L<<0)   /* (input) use image buffer */
#define codecFlagUseScreenBuffer(1L<<1)   /* (input) use screen buffer */
#define codecFlagUpdatePrevious (1L<<2)   /* (input) update previous 
                                              buffer */
#define codecFlagNoScreenUpdate (1L<<3)   /* (input) don't update screen */
#define codecFlagWasCompressed  (1L<<4)   /* (input) image compressed */
#define codecFlagDontOffscreen  (1L<<5)   /* don't go offscreen
                                              automatically */
#define codecFlagUpdatePreviousComp (1L<<6)
                                          /* (input) update previous 
                                              buffer */
#define codecFlagForceKeyFrame (1L<<7)    /* force key frame from image */ 
#define codecFlagOnlyScreenUpdate 
                               (1L<<8)    /* decompress current frame */
#define codecFlagLiveGrab  (1L<<9)        /* sequence from live video grab */
#define codecFlagDontUseNewImageBuffer (1L<<10)
                                          /* (input) don't use new image
                                              buffer */
#define codecFlagInterlaceUpdate (1L<<11)
                                          /* (input) update screen
                                              interlacing */
/* 
   status flags from outflags parameter of DecompressSequenceFrame 
   function 
*/
#define  codecFlagUsedNewImageBuffer (1L<<14)
                                       /* (output) used new image buffer */
#define  codecFlagUsedImageBuffer (1L<<15)
                                       /* (output) used image buffer */

/* completion flags from application-defined completion functions */
#define  codecCompletionSource (1<<0) /* Image Compression Manager done 
                                        with source buffer */
#define  codecCompletionDest   (1<<1)/* Image Compression Manager done with
                                        destination buffer */

/* compression quality values */
#define codecMinQuality       0x000L /* minimum-quality image reproduction */
#define codecLowQuality       0x100L /* low-quality image reproduction */
#define codecNormalQuality    0x200L /* normal-quality image reproduction */
#define codecHighQuality      0x300L /* high-quality image reproduction */
#define codecMaxQuality       0x3FFL /* maximum-quality image reproduction */
#define codecLosslessQuality  0x400L /* lossless-quality reproduction */

/* 
   special compressor and decompressor identifiers let you choose an 
   image compressor component 
*/
#define anyCodec              (CodecComponent)0)   /* first one or a
                                                      specified type */
#define bestSpeedCodec        ((CodecComponent)-1) /* fastest of specified
                                                      type */
#define bestFidelityCodec     (CodecComponent)-2)  /* most accurate of
                                                      specified type */
#define bestCompressionCodec( (CodecComponent)-3)  /* one with smallest
                                                      resulting data */
/* 
   constants for doDither parameter of DrawTrimmedPictureFile and
   FCompressPictureFile functions 
*/
#define defaultDither0     /* respect dithering instructions in 
                               source picture */
#define forceDither1       /* dither image */
#define suppressDither2    /* don't dither image */

Data Types

typedef Component CompressorComponent; /* compressor identifier */
typedef Component DecompressorComponent;/* decompressor identifier */
typedef Component CodecComponent;      /* compressor identifier */
      
typedef long CodecType;                /* compressor type */
   
typedef unsigned short CodecFlags;     /* compressor component flags */ 
   
typedef unsigned long CodecQ;          /* compression quality */

typedef pascal OSErr (*DataProcPtr) (Ptr *dataP, long bytesNeeded, 
                      longrefCon);  /* pointer to a data-loading function */

typedef pascal OSErr (*FlushProcPtr) (Ptr data, long bytesAdded, 
                      long refCon);/* pointer to a data-unloading function */

typedef pascal void (*CompletionProcPtr)(OSErr result, short flags, 
                      long refCon);/* pointer to a completion function */
typedef pascal OSErr (*ProgressProcPtr)(short message, Fixed completeness,
                      long refCon);/* pointer to a progress function */
typedef long ImageSequence;      /* unique sequence identifier */

/* progress function structure */
struct ProgressProcRecord 
{
      ProgressProcPtr progressProc; /* pointer to your progress function */
      long progressRefCon;          /* reference constant */
};
typedef struct ProgressProcRecord ProgressProcRecord; 
typedef ProgressProcRecord *ProgressProcRecordPtr;
/* completion function structure */
struct CompletionProcRecord 
{
      CompletionProcPtr completionProc;/* pointer to completion function */
      long completionRefCon;           /* reference constant */
};
typedef struct CompletionProcRecord CompletionProcRecord;
typedef CompletionProcRecord *CompletionProcRecordPtr;

/* data-loading structure */
struct DataProcRecord 
{
      DataProcPtr dataProc;            /* pointer to data-loading function */
      long dataRefCon;                 /* reference constant */
};
typedef struct DataProcRecord DataProcRecord;
typedef DataProcRecord *DataProcRecordPtr;

/* data-unloading structure */
struct FlushProcRecord 
{
      FlushProcPtr flushProc; /* pointer to data-unloading function */
      long flushRefCon;       /* reference constant */
};
typedef struct FlushProcRecord FlushProcRecord;
typedef FlushProcRecord *FlushProcRecordPtr;
typedef pascal void (*StdPixProcPtr)(PixMap *src, Rect *srcRect,
                                     MatrixRecord *matrix, 
                                     short mode, RgnHandle mask, 
                                     PixMap *matte,Rect *matteRect, 
                                     short flags);
typedef struct 
{
   AlignmentProcPtr     alignmentProc;    /* pointer to your alignment
                                             function */
   long                 alignmentRefCon;  /* reference constant */
} AlignmentProcRecord;
typedef AlignmentProcRecord *AlignmentProcRecordPtr;
typedef struct 
{
   long     dataRate;               /* bytes per second */
   long     dataOverrun;            /* number of bytes outside rate */
   long     frameDuration;          /* in milliseconds */
   long     keyFrameRate;           /* frequency of key frames */
   CodecQ   minSpatialQuality;      /* minimum spatial quality */
   CodecQ   minTemporalQuality;     /* minimum temporal quality */
} DataRateParams;
typedef DataRateParams *DataRateParamsPtr;
/* image description structure */
struct ImageDescription 
{
      long idSize;            /* total size of this structure */
      CodecType cType;        /* compressor type of creator */
      long resvd1;            /* reserved--must be set to 0 */
      short resvd2;           /* reserved--must be set to 0 */
      short dataRefIndex;     /* reserved--must be set to 0 */
      short version;          /* version of compressed data */
      short revisionLevel;    /* version of compressor that created data */
      long vendor;            /* developer of compressor that created data */
      CodecQ temporalQuality; /* degree of temporal compression */
      CodecQ spatialQuality;  /* degree of spatial compression */
      short width;            /* width of source image in pixels */
      short height;           /* height of source image in pixels */
      Fixed hRes;             /* horizontal resolution of source image */
      Fixed vRes;             /* vertical resolution of source image */
      long dataSize;          /* size in bytes of compressed data */
      short frameCount;       /* number of frames in image data */
      Str31 name;             /* name of compression algorithm */
      short depth;            /* pixel depth of source image */
      short clutID;           /* ID number of color table for image */
};
typedef struct ImageDescription ImageDescription;
typedef ImageDescription *ImageDescriptionPtr, **ImageDescriptionHandle;

/* compressor information structure */
struct CodecInfo 
{
      Str31 typeName;            /* compression algorithm */
      short version;             /* version of compressed data */
      short revisionLevel;       /* version of component */
      long vendor;               /* developer of component */
      long decompressFlags;      /* decompression capability flags */
      long compressFlags;        /* compression capability flags */
      long formatFlags;          /* compression format flags */
      unsigned char compressionAccuracy;
                                 /* relative accuracy of compression */
      unsigned char decompressionAccuracy;
                                 /* relative accuracy of decompression */
      unsigned short compressionSpeed;
                                 /* relative speed of compressor */
      unsigned short decompressionSpeed;
                                 /* relative speed of decompressor */
      unsigned char compressionLevel;
                                 /* relative level of compression */
      char resvd;                /* reserved--set to 0 */
      short minimumHeight;       /* minimum height */
      short minimumWidth;        /* minimum width */
      short decompressPipelineLatency;
                                 /* in milliseconds (asynchronous) */
      short compressPipelineLatency;
                                 /* in milliseconds (asynchronous) */
      long privateData;          /* reserved for use by Apple */
};
typedef struct CodecInfo CodecInfo;
/* compressor name structure returned by GetCodecNameList function */
struct CodecNameSpec 
{
      CodecComponent codec;/* component ID for compressor */
      CodecType cType;     /* type identifier for compressor */
      Str31 typeName;      /* string identifier of compression algorithm */
      Handle name;         /* name of compressor component */
};
typedef struct CodecNameSpec CodecNameSpec;

/* compressor name list structure */
struct CodecNameSpecList 
{
      short count;            /* number of compressor name structures in list
                                 array that follows */
      CodecNameSpec list[1];  /* array of compressor name structures */
};
typedef struct CodecNameSpecList CodecNameSpecList;
typedef CodecNameSpecList *CodecNameSpecListPtr;
/* 
   flags from message parameter of application-defined progress functions
   tell why the Image Compression Manager called your function 
*/
enum 
{
   codecProgressOpen          = 0,  /* start of a long operation */ 
   codecProgressUpdatePercent = 1,  /* passes completion information */
   codecProgressClose         = 2   /* end of a long operation*/
};
typedef pascal void (*CompletionProcPtr) (OSErr result, short flags, 
                     long refCon);
/* data rate parameters structure */
typedef struct {
   long     dataRate;               /* bytes per second */
   long     dataOverrun;            /* number of bytes outside rate */
   long     frameDuration;          /* in milliseconds */
   long     keyFrameRate;           /* frequency of key frames */
   CodecQ   minSpatialQuality;      /* minimum spatial quality */
   CodecQ   minTemporalQuality;     /* minimum temporal quality */
} DataRateParams;
typedef DataRateParams *DataRateParamsPtr;

Image Compression Manager Functions

Getting Information About Compressor Components

pascal OSErr CodecManagerVersion
				(long *version);
pascal OSErr GetCodecNameList
				(CodecNameSpecListPtr *list, short showAll);
pascal OSErr DisposeCodecNameList
				(CodecNameSpecListPtr list);
pascal OSErr GetCodecInfo	(CodecInfo *info, CodecType cType, 
				CodecComponent codec);
pascal OSErr FindCodec		(CodecType cType, CodecComponent specCodec, 
				CompressorComponent *compressor,
				DecompressorComponent *decompressor);

Getting Information About Compressed Data

pascal OSErr GetMaxCompressionSize
				(PixMapHandle src, const Rect *srcRect, 
				short colorDepth, CodecQ quality, 
				CodecType cType, CompressorComponent codec, long *size);
pascal OSErr GetCompressionTime
				(PixMapHandle src, const Rect *srcRect, 
				short colorDepth, CodecType cType, CompressorComponent codec, 
				CodecQ *spatialQuality, 
				CodecQ *temporalQuality,
				unsigned long *compressTime);
pascal OSErr GetSimilarity	(PixMapHandle src, const Rect *srcRect, 
				ImageDescriptionHandle desc, Ptr data,
				Fixed *similarity);
pascal OSErr GetCompressedImageSize
				(ImageDescriptionHandle desc, Ptr data,
				long bufferSize, DataProcRecordPtr dataProc, long *dataSize);

Working With Images

pascal OSErr CompressImage	(PixMapHandle src, const  Rect *srcRect,
				CodecQ quality, CodecType cType,
				ImageDescriptionHandle desc, Ptr data);
pascal OSErr FCompressImage
				(PixMapHandle src, const  Rect *srcRect, 
				short colorDepth, CodecQ quality, 
				CodecType cType, CompressorComponent codec, CTabHandle clut, CodecFlags flags, 
				long bufferSize, FlushProcRecordPtr flushProc, ProgressProcRecordPtr progressProc, ImageDescriptionHandle desc, Ptr data);
pascal OSErr DecompressImage
				(Ptr data, ImageDescriptionHandle desc, PixMapHandle dst, const Rect *srcRect, 
				const  Rect *dstRect, short mode, 
				RgnHandle mask);
pascal OSErr FDecompressImage
				(Ptr data, ImageDescriptionHandle desc, PixMapHandle dst, const  Rect *srcRect, MatrixRecordPtr matrix, short mode, 
				RgnHandle mask, PixMapHandle matte, 
				const  Rect *matteRect, CodecQ accuracy, DecompressorComponent codec, long bufferSize, DataProcRecordPtr dataProc, ProgressProcRecordPtr progressProc);
pascal OSErr ConvertImage	(ImageDescriptionHandle srcDD, Ptr srcData, 
				short colorDepth, CTabHandle clut, 
				CodecQ accuracy, CodecQ quality, 
				CodecType cType, CodecComponent codec, 
				ImageDescriptionHandle dstDD, Ptr dstData);
pascal OSErr TrimImage		(ImageDescriptionHandle desc, Ptr inData, 
				long inBufferSize, DataProcRecordPtr dataProc, 
				Ptr outData, long outBufferSize, 
				FlushProcRecordPtr flushProc, Rect *trimRect, 
				ProgressProcRecordPtr progressProc);
pascal OSErr SetImageDescriptionCTable
				(ImageDescriptionHandle desc, 
				CTabHandle ctable);
pascal OSErr GetImageDescriptionCTable
				(ImageDescriptionHandle desc, 
				CTabHandle *ctable);

Working With Pictures and PICT Files

pascal OSErr CompressPicture
				(PicHandle srcPicture, PicHandle dstPicture, CodecQ quality, CodecType cType);
pascal OSErr FCompressPicture
				(PicHandle srcPicture, PicHandle dstPicture, short colorDepth, CTabHandle clut, 
				CodecQ quality, short doDither, 
				short compressAgain, 
ProgressProcRecordPtr progressProc,
				CodecType cType, CompressorComponent codec);
pascal OSErr CompressPictureFile
				(short srcRefNum, short dstRefNum, 
				CodecQ quality, CodecType cType);
pascal OSErr FCompressPictureFile
				(short srcRefNum, short dstRefNum, 
				short colorDepth, CTabHandle clut, 
				CodecQ quality, short doDither, 
				short compressAgain, 
				ProgressProcRecordPtr progressProc,
				CodecType cType, CompressorComponent codec);
pascal OSErr DrawPictureFile
				(short refNum, const Rect *frame, ProgressProcRecordPtr progressProc);
pascal OSErr DrawTrimmedPicture
				(PicHandle srcPicture, const Rect *frame, RgnHandle trimMask, short doDither, ProgressProcRecordPtr progressProc);
pascal OSErr DrawTrimmedPictureFile
				(short srcRefnum, const Rect *frame, 
				RgnHandle trimMask, short doDither, ProgressProcRecordPtr progressProc);
pascal OSErr GetPictureFileHeader
				(short refNum, Rect *frame, 
				OpenCPicParams *header);

Making Thumbnail Pictures

pascal OSErr MakeThumbnailFromPicture
				(PicHandle picture, short colorDepth, 
				PicHandle thumbnail, 
				ProgressProcRecordPtr progressProc);
pascal OSErr MakeThumbnailFromPictureFile
				(short refNum, short colorDepth, 
				PicHandle thumbnail, 
				ProgressProcRecordPtr progressProc);
pascal OSErr MakeThumbnailFromPixMap
				(PixMapHandle src, const Rect *srcRect, 
				short colorDepth, PicHandle thumbnail, ProgressProcRecordPtr progressProc);

Working With Sequences

pascal OSErr CompressSequenceBegin
				(ImageSequence *seqID, PixMapHandle src, PixMapHandle prev, const Rect *srcRect, 
				const  Rect *prevRect, short colorDepth, CodecType cType, CompressorComponent codec, CodecQ spatialQuality, CodecQ temporalQuality, long keyFrameRate, CTabHandle clut, 
				CodecFlags flags, ImageDescriptionHandle desc);
pascal OSErr CompressSequenceFrame
				(ImageSequence seqID, PixMapHandle src, 
				const Rect *srcRect, CodecFlags flags, 
Ptr data, long *dataSize, 
				unsigned char *similarity, CompletionProcRecordPtr asyncCompletionProc);
pascal OSErr DecompressSequenceBegin
				(ImageSequence *seqID, 
				ImageDescriptionHandle desc, CGrafPtr port, GDHandle gdh, const Rect *srcRect, MatrixRecordPtr matrix, short mode, 
				RgnHandle mask, CodecFlags flags, 
				CodecQ accuracy, DecompressorComponent codec);
pascal OSErr DecompressSequenceFrame
				(ImageSequence seqID, Ptr data, 
				CodecFlags inFlags, CodecFlags *outFlags, CompletionProcRecordPtr asyncCompletionProc);
pascal OSErr CDSequenceBusy
				(ImageSequence seqID);
pascal OSErr CDSequenceEnd	(ImageSequence seqID);

Changing Sequence-Compression Parameters

pascal OSErr SetCSequenceQuality
				(ImageSequence seqID, CodecQ spatialQuality, CodecQ temporalQuality);
pascal OSErr SetCSequenceKeyFrameRate
				(ImageSequence seqID, long keyframerate);
pascal OSErr GetCSequenceKeyFrameRate
				(ImageSequence seqID, long *keyframerate);
pascal OSErr SetCSequenceFrameNumber
				(ImageSequence seqID, long frameNumber);
pascal OSErr GetCSequenceFrameNumber
				(ImageSequence seqID, long *frameNumber);
pascal OSErr SetCSequencePrev
				(ImageSequence seqID, PixMapHandle prev, 
const Rect *prevRect);
pascal OSErr SetCSequenceFlushProc
				(ImageSequence seqID, 
				FlushProcRecordPtr flushProc, long bufferSize);
pascal OSErr GetCSequencePrevBuffer
				(ImageSequence seqID, GWorldPtr *gworld);

Constraining Compressed Data

pascal OSErr SetCSequenceDataRateParams
				(ImageSequence seqID, 
				DataRateParamsPtr params);
pascal OSErr GetCSequenceDataRateParams
				(ImageSequence seqID, DataRateParamsPtr params);

Changing Sequence-Decompression Parameters

pascal OSErr SetDSequenceTransferMode
				(ImageSequence seqID, short mode, 
				const RGBColor *opColor);
pascal OSErr SetDSequenceSrcRect
				(ImageSequence seqID, const Rect *srcRect);
pascal OSErr SetDSequenceMatrix
				(ImageSequence seqID, MatrixRecordPtr matrix);
pascal OSErr SetDSequenceMask
				(ImageSequence seqID, RgnHandle mask);
pascal OSErr SetDSequenceMatte
				(ImageSequence seqID, PixMapHandle matte,
				const Rect *matteRect);
pascal OSErr SetDSequenceAccuracy
				(ImageSequence seqID, CodecQ accuracy);
pascal OSErr SetDSequenceDataProc
				(ImageSequence seqID, 
				DataProcRecordPtr dataProc, long bufferSize);
pascal OSErr GetDSequenceImageBuffer
				(ImageSequence seqID, GWorldPtr *gworld);
pascal OSErr GetDSequenceScreenBuffer
				(ImageSequence seqID, GWorldPtr *gworld);

Working With the StdPix Function

pascal void StdPix		(PixMapPtr src, const  Rect *srcRect, 
				MatrixRecordPtr matrix, short mode, 
				RgnHandle mask, PixMapPtr matte, 
				Rect *matteRect, short flags);
pascal OSErr SetCompressedPixMapInfo
				(PixMapPtr pix, ImageDescriptionHandle desc, Ptr data, long bufferSize,
				DataProcRecordPtr dataProc, ProgressProcRecordPtr progressProc);
pascal OSErr GetCompressedPixMapInfo
				(PixMapPtr pix, ImageDescriptionHandle *desc, Ptr *data, long *bufferSize, 
				DataProcRecord *dataProc, 
				ProgressProcRecord *progressProc);

Aligning Windows

pascal void AlignWindow 	(WindowPtr wp, Boolean front, 
				const Rect *alignmentRect, 
				AlignmentProcRecordPtr alignmentProc);
pascal void DragAlignedWindow
				(WindowPtr wp, Point startPt, 
				Rect *boundsRect, Rect *alignmentRect, AlignmentProcRecordPtr alignmentProc);
pascal long DragAlignedGrayRgn
				(RgnHandle theRgn, Point startPt, 
				Rect *boundsRect, Rect *slopRect, short axis, ProcPtr actionProc, Rect *alignmentRect,
				AlignmentProcRecordPtr alignmentProc);
pascal void AlignScreenRect
				(Rect *rp, 
				AlignmentProcRecordPtr alignmentProc);

Working With Graphics Devices and Graphics Worlds

pascal OSErr GetBestDeviceRect
				(GDHandle *gdh, Rect *rp);
pascal QDErr NewImageGWorld
				(GWorldPtr *gworld,
				ImageDescription **idh,GWorldFlags flags);

Application-Defined Functions

Data-Loading Functions

pascal OSErr MyDataLoadingProc
				(Ptr *dataP, long bytesNeeded, long refcon);

Data-Unloading Functions

pascal OSErr MyDataUnloadingProc
				(Ptr data, long bytesAdded, long refcon);

Progress Functions

pascal  OSErr MyProgressProc
				(short message, Fixed completeness, 
				long refcon);

Completion Functions

pascal OSErr MyCompletionProc
				(OSErr result, short flag, long refcon);

Alignment Functions

pascal void MyAlignmentProc
				(Rect *rp, long refcon);

Pascal Summary

Constants

CONST
   gestaltCompressionMgr            = 'icmp';{determines if Image }
                                             { Compression Manager is }
                                             { available}

   codecMinimumDataSize             = 32768; {smallest data buffer you may }
                                             { allow for data spooling}
   compressorComponentType          = 'imco';{compressor component type}
   decompressorComponentType        = 'imdc';{decompressor component type}

   {Image Compression Manager function control flags}
   codecFlagUseImageBuffer          = $1;    {(input) use offscreen buffer}
   codecFlagUseScreenBuffer         = $2;    {(input) use screen buffer}
   codecFlagUpdatePrevious          = $4;    {(input) previous image is }
                                             { updated}
   codecFlagNoScreenUpdate          = $8;    {(input) no screen image update}
   codecFlagWasCompressed           = $10;   {(input) image has been }
                                             { compressed} 
   codecFlagDontOffscreen           = $20;   {don't use offscreen buffer}
   codecFlagUpdatePreviousComp      = $40;   {(input) previous image buffer }
                                             { updated}
   codecFlagForceKeyFrame           = $80;   {force key frame from image} 
   codecFlagOnlyScreenUpdate        = $100;  {decompresses current frame}
   codecFlagLiveGrab                = $200;  {sequence from live video grab}
   codecFlagDontUseNewImageBuffer   = $400;  {(input) return error if image }
                                             { buffer is new or reallocated}
   codecFlagInterlaceUpdate         = $800;  {(input) use interlaced update}
{status flags from outflags parameter of DecompressSequenceFrame function}
   codecFlagUsedNewImageBuffer      = $4000; {(output) used new image buffer}
   codecFlagUsedImageBuffer         = $8000; {(output) used offscreen image }
                                             { buffer}

   {completion flags from application-defined completion functions}
   codecCompletionSource            = 1;     {done with source buffer} 
   codecCompletionDest              = 2;     {done with destination buffer}

   {flags from application-defined progress functions message parameter--- }
   { tell why the Image Compression Manager called your function}
   codecProgressOpen                = 0;     {start of a long operation} 
   codecProgressUpdatePercent       = 1;     {passing completion data}
   codecProgressClose               = 2;     {end of a long}

   {compression quality values}
   codecMinQuality         = $000;  {minimum-quality image reproduction}
   codecLowQuality         = $100;  {low-quality image reproduction}
   codecNormalQuality      = $200;  {normal-quality image reproduction}
   codecHighQuality        = $300;  {high-quality image reproduction}
   codecMaxQuality         = $3FF;  {maximum-quality image reproduction}
   codecLosslessQuality    = $400;  {lossless-quality image reproduction}
   
   {special compressor and decompressor identifiers}
   anyCodec                =  0; {first component of specified type}
   bestSpeedCodec          = -1; {fastest component of specified type}
   bestFidelityCodec       = -2; {most accurate component of specified type}
   bestCompressionCodec    = -3; {component with smallest resulting data}
{constants for doDither parameter of DrawTrimmedPictureFile and }
{ FCompressPictureFile functions}
defaultDither        = 0;  {respect dithering instructions in source }
                              { picture}
   forceDither          = 1;  {dither image}
   suppressDither       = 2;  {don't dither image}

Data Types

TYPE
   CompressorComponent              = Component;{compressor identifier}
   DecompressorComponent            = Component;{decompressor identifier}
   CodecComponent                   = Component;{compressor identifier}
   
   CodecType                        = OSType;   {compressor type}
   
   CodecFlags                       = Integer;  {compressor component flags} 
   
   CodecQ                           = LongInt;  {compression quality}

   DataProcPtr             = ProcPtr;  {pointer to a data-loading function}
   FlushProcPtr            = ProcPtr;  {pointer to a data-unloading function}
   CompletionProcPtr       = ProcPtr;  {pointer to a completion function}
   ProgressProcPtr         = ProcPtr;  {pointer to a progress function}
   
   ImageSequence           = LongInt;  {unique sequence identifer}

   ProgressProcRecordPtr   = ^ProgressProcRecord;
   ProgressProcRecord =                   {progress function record}
   RECORD
      progressProc:     ProgressProcPtr;  {pointer to your progress function}
      progressRefCon:   LongInt;          {reference constant}
   END;
   
   CompletionProcRecordPtr = ^CompletionProcRecord;
   CompletionProcRecord =                 {completion function record}
   RECORD
      completionProc:   CompletionProcPtr;{pointer to completion function}
      completionRefCon: LongInt;          {reference constant}
   END;
   
   DataProcRecordPtr             = ^DataProcRecord;
   DataProcRecord =                       {data-loading function record}
   RECORD
      dataProc:   DataProcPtr;            {pointer to data-loading function}
      dataRefCon: LongInt;                {reference constant}
   END;
   
   FlushProcRecordPtr            = ^FlushProcRecord;
   FlushProcRecord =                      {data-unloading function record}
   RECORD
      flushProc:     FlushProcPtr;        {pointer to data-unloading } 
                                          { function}
      flushRefCon:   LongInt;             {reference constant}
   END;
ImageDescriptionPtr                 = ^ImageDescription;
   ImageDescriptionHandle              = ^ImageDescriptionPtr;
   ImageDescription = 
   PACKED RECORD
      idSize:           LongInt;          {total size of this record}
      cType:            CodecType;        {type of creator component}
      resvd1:           LongInt;          {reserved---must be set to 0}
      resvd2:           Integer;          {reserved---must be set to 0}
      dataRefIndex:     Integer;          {reserved---must be set to 0}
      version:          Integer;          {version of compressed data}
      revisionLevel:    Integer;          {version of creator compressor}
      vendor:           LongInt;          {developer of creator compressor}
      temporalQuality:  CodecQ;           {degree of temporal compression}
      spatialQuality:   CodecQ;           {degree of spatial compression}
      width:            Integer;    {width of source image in pixels}
      height:           Integer;    {height of source image in pixels}
      hRes:             Fixed;      {horizontal resolution of source image}
      vRes:             Fixed;      {vertical resolution of source image}
      dataSize:         LongInt;    {byte size of compressed image data}
      frameCount:       Integer;    {number of frames in image data}
      name:             PACKED ARRAY[0..31] of char;
                                    {name of compression algorithm}
      depth:            Integer;    {pixel depth of source image}
      clutID:           Integer; {ID number of the color table for image}
   END;
   
   CodecInfo =                         {compressor information record}
   PACKED RECORD
      typeName:            PACKED ARRAY[0..31] of char;
                                       {compression algorithm}
      version:             Integer;    {version of compressed data}
      revisionLevel:       Integer;    {version of component}
      vendor:              LongInt;    {developer of component}
      decompressFlags:     LongInt;    {decompression capability flags}
      compressFlags:       LongInt;    {compression capability flags}
      formatFlags:         LongInt;    {format flags}
      compressionAccuracy:
                           Char;       {relative accuracy of compression}
      decompressionAccuracy:
                           Char;       {relative accuracy of decompression}
      compressionSpeed:    Integer;    {relative compression speed}
      decompressionSpeed:  Integer;    {relative decompression speed}
      compressionLevel:    Char;       {relative compression of component}
      resvd:               Char;       {reserved---set to 0}
      minimumHeight:       Integer;    {minimum height in pixels}
      minimumWidth:        Integer;    {maximum width in pixels}
      decompressPipelineLatency:
                           Integer;    {milliseconds (asynchronous)}
      compressPipelineLatency:
                           Integer;    {milliseconds (asynchronous)}
      privateData:         LongInt;    {reserved--must be set to 0}
   END;
   
   {compressor name record returned by GetCodecNameList}
   CodecNameSpec = 
   PACKED RECORD
      codec:      CodecComponent;{component ID for compressor}
      cType:      CodecType;     {type identifier for compressor}
      typeName:   PACKED ARRAY[0..31] OF Char;
                                 {string identifier of compression algorithm}
      name:       Handle;        {name of compressor component}
   END;
{compressor name list record}
   CodecNameSpecListPtr             = ^CodecNameSpecList;
   CodecNameSpecList = 
   RECORD
      count:      Integer;             {number of compressor name records}
      list:       ARRAY[0..0] OF CodecNameSpec;
                                       {array of compressor name records}
   END;
{data rate parameters record}
   DataRateParamsPtr = ^DataRateParams;
   DataRateParams = 
   RECORD
      dataRate:            LongInt;    {bytes per second}
      dataOverrun:         LongInt;    {number of bytes outside rate}
      frameDuration:       LongInt;    {duration in milliseconds}
      keyFrameRate:        LongInt;    {frequency of key frames}
      minSpatialQuality:   CodecQ;     {minimum spatial quality}
      minTemporalQuality:  CodecQ;     {minimum temporal quality}
    END;

Image Compression Manager Routines

Getting Information About Compressor Components

FUNCTION CodecManagerVersion
				(VAR version: LongInt): OSErr;
FUNCTION GetCodecNameList 	(VAR list: CodecNameSpecListPtr; 
				showAll: Integer): OSErr;
FUNCTION DisposeCodecNameList
				(list: CodecNameSpecListPtr): OSErr;
FUNCTION GetCodecInfo 		(VAR info: CodecInfo; cType: CodecType; 
				codec: CodecComponent): OSErr;
FUNCTION FindCodec	 	(cType: CodecType; specCodec: CodecComponent; 
				VAR compressor: CompressorComponent; 
				VAR decompressor: DecompressorComponent): 
				OSErr;

Getting Information About Compressed Data

FUNCTION GetMaxCompressionSize 
				(src: PixMapHandle; srcRect: Rect; 
				colorDepth: Integer; quality: CodecQ; 
				cType: CodecType; codec: CompressorComponent; VAR size: LongInt): OSErr;
FUNCTION GetCompressionTime 
				(src: PixMapHandle; srcRect: Rect; 
				colorDepth: Integer; cType: CodecType; 
				codec: CompressorComponent; 
				VAR spatialQuality: CodecQ; 
				VAR temporalQuality: CodecQ; 
				VAR compressTime: LongInt): OSErr;
FUNCTION GetSimilarity 		(src: PixMapHandle; srcRect: Rect; 
				desc: ImageDescriptionHandle; data: Ptr; 
				VAR similarity: Fixed): OSErr;
FUNCTION GetCompressedImageSize 
				(desc: ImageDescriptionHandle; data: Ptr; bufferSize: LongInt; 
				dataProc: DataProcRecordPtr; 
				VAR dataSize: LongInt): OSErr;

Working With Images

FUNCTION CompressImage 		(src: PixMapHandle; srcRect: Rect; 
				quality: CodecQ; cType: CodecType; 
				desc: ImageDescriptionHandle; 
				data: Ptr): OSErr;
FUNCTION FCompressImage	 	src: PixMapHandle; srcRect: Rect; 
				colorDepth: Integer; quality: CodecQ; 
				cType: CodecType; codec: CompressorComponent; 
				clut: CTabHandle; flags: CodecFlags; 
				bufferSize: LongInt; 
				flushProc: FlushProcRecordPtr; 
				progressProc: ProgressProcRecordPtr; 
				desc: ImageDescriptionHandle; 
				data: Ptr): OSErr;
FUNCTION DecompressImage 	(data: Ptr; desc: ImageDescriptionHandle; 
				dst: PixMapHandle; srcRect: Rect; 
				dstRect: Rect; mode: Integer;
				mask: RgnHandle): OSErr;
FUNCTION FDecompressImage	 (data: Ptr; desc: ImageDescriptionHandle; 
				dst: PixMapHandle; srcRect: Rect; 
				matrix: MatrixRecordPtr; mode: Integer; 
				mask: RgnHandle; matte: PixMapHandle; 
				matteRect: Rect; accuracy: CodecQ; 
				codec: DecompressorComponent; 
				bufferSize: LongInt; 
				dataProc: DataProcRecordPtr; 
				progressProc: ProgressProcRecordPtr): OSErr;
FUNCTION ConvertImage	 	(srcDD: ImageDescriptionHandle; srcData: Ptr; 
				colorDepth: Integer; clut: CTabHandle; 
				accuracy: CodecQ; quality: CodecQ; 
				cType: CodecType; codec: CodecComponent; 
				dstDD: ImageDescriptionHandle; 
				dstData: Ptr): OSErr;
FUNCTION TrimImage 		(desc: ImageDescriptionHandle; inData: Ptr; 
				inBufferSize: LongInt; 
				dataProc: DataProcRecordPtr; outData: Ptr; 
				outBufferSize: LongInt; 
				flushProc: FlushProcRecordPtr; 
				VAR trimRect: Rect; 
				progressProc: ProgressProcRecordPtr): OSErr;
FUNCTION SetImageDescriptionCTable 
				(desc: ImageDescriptionHandle; 
				ctable: CTabHandle): OSErr;
FUNCTION GetImageDescriptionCTable 
				(desc: ImageDescriptionHandle; 
				VAR ctable: CTabHandle): OSErr;

Working With Pictures and PICT Files

FUNCTION CompressPicture 	(srcPicture: PicHandle; dstPicture: PicHandle; 
				quality: CodecQ; cType: CodecType): OSErr;
FUNCTION FCompressPicture	 (srcPicture: PicHandle; dstPicture: PicHandle; 
				colorDepth: Integer; clut: CTabHandle; 
				quality: CodecQ; doDither: Integer; 
				compressAgain: Integer; 
				progressProc: ProgressProcRecordPtr; 
				cType: CodecType; 
				codec: CompressorComponent): OSErr;
FUNCTION CompressPictureFile
				(srcRefNum: Integer; dstRefNum: Integer; quality: CodecQ; cType: CodecType): OSErr;
FUNCTION FCompressPictureFile
				(srcRefNum: Integer; dstRefNum: Integer; colorDepth: Integer; clut: CTabHandle; quality: CodecQ; doDither: Integer; compressAgain: Integer; 
				progressProc: ProgressProcRecordPtr; 
				cType: CodecType; 
				odec: CompressorComponent): OSErr;
FUNCTION DrawPictureFile 	(refNum: Integer; frame: Rect; 
				progressProc: ProgressProcRecordPtr): OSErr;
FUNCTION DrawTrimmedPicture 
				(srcPicture: PicHandle; frame: Rect; 
				trimMask: RgnHandle; doDither: Integer; progressProc: ProgressProcPtr): OSErr;
FUNCTION DrawTrimmedPictureFile 
				(srcRefnum: Integer; frame: Rect; 
				trimMask: RgnHandle; doDither: Integer; progressProc: ProgressProcRecordPtr): OSErr;
FUNCTION GetPictureFileHeader
				(refNum: Integer; VAR frame: Rect; 
				VAR header: OpenCPicParams): OSErr;

Making Thumbnail Pictures

FUNCTION MakeThumbnailFromPicture 
				(picture: PicHandle; colorDepth: Integer; thumbnail: PicHandle; 
				progressProc: ProgressProcRecordPtr): OSErr;
FUNCTION MakeThumbnailFromPictureFile 
				(refNum: Integer; colorDepth: Integer; thumbnail: PicHandle; 
				progressProc: ProgressProcRecordPtr): OSErr;
FUNCTION MakeThumbnailFromPixMap 
				(src: PixMapHandle; srcRect: Rect; 
				colorDepth: Integer; thumbnail: PicHandle; 
				progressProc: ProgressProcRecordPtr): OSErr;

Working With Sequences

FUNCTION CompressSequenceBegin 
				(VAR seqID: ImageSequence; 
				src: PixMapHandle; prev: PixMapHandle; srcRect: Rect; prevRect: Rect; 
				colorDepth: Integer; cType: CodecType; 
				codec: CompressorComponent; 
				spatialQuality: CodecQ; 
				temporalQuality: CodecQ; 
				keyFrameRate: LongInt; clut: CTabHandle; flags: CodecFlags; 
				desc: ImageDescriptionHandle): OSErr;
FUNCTION CompressSequenceFrame 
				(seqID: ImageSequence; 
				src: PixMapHandle; srcRect: Rect; 
				flags: CodecFlags; data: Ptr; 
				VAR dataSize: LongInt; VAR similarity: Char; 
				asyncCompletionProc: CompletionProcRecordPtr): OSErr;
FUNCTION DecompressSequenceBegin 
				(VAR seqID: ImageSequence; 
				desc: ImageDescriptionHandle; port: CGrafPtr; gdh: GDHandle; srcRect: Rect; 
				matrix: MatrixRecordPtr; mode: Integer; 
				mask: RgnHandle; flags: CodecFlags; 
				accuracy: CodecQ; 
				codec: DecompressorComponent): OSErr;
FUNCTION DecompressSequenceFrame 
				(seqID: ImageSequence; data: Ptr; 
				inFlags: CodecFlags; VAR outFlags: CodecFlags; asyncCompletionProc: CompletionProcRecordPtr): OSErr;
FUNCTION CDSequenceBusy 	(seqID: ImageSequence): OSErr;
FUNCTION CDSequenceEnd 	(seqID: ImageSequence): OSErr;

Changing Sequence-Compression Parameters

FUNCTION SetCSequenceQuality 
				(seqID: ImageSequence; spatialQuality: CodecQ; temporalQuality: CodecQ): OSErr;
FUNCTION SetCSequenceKeyFrameRate 
				(seqID: ImageSequence; 
				keyframerate: LongInt): OSErr;
FUNCTION GetCSequenceKeyFrameRate
				(seqID: ImageSequence; 
				VAR keyframerate: LongInt): OSErr;
FUNCTION GetCSequenceKeyFrameRate
				(seqID: ImageSequence; 
				VAR keyframerate: LongInt): OSErr;
FUNCTION SetCSequenceFrameNumber
				(seqID: ImageSequence; 
				frameNumber: LongInt): OSErr;
FUNCTION GetCSequenceFrameNumber
				(seqID: ImageSequence; 
				VAR frameNumber: LongInt): OSErr;
FUNCTION SetCSequencePrev 	(seqID: ImageSequence; prev: PixMapHandle; 
				prevRect: Rect): OSErr;
FUNCTION SetCSequenceFlushProc 
				(seqID: ImageSequence; 
				flushProc: FlushProcRecordPtr; 
				bufferSize: LongInt): OSErr;
FUNCTION GetCSequencePrevBuffer 
				(seqID: ImageSequence; 
				VAR gworld: GWorldPtr): OSErr;

Constraining Compressed Data

FUNCTION SetCSequenceDataRateParams
				(seqID: ImageSequence; 
				params: DataRateParamsPtr): OSErr;
FUNCTION GetCSequenceDataRateParams
				(seqID: ImageSequence; 
				params: DataRateParamsPtr): OSErr;

Changing Sequence-Decompression Parameters

FUNCTION SetDSequenceTransferMode 
				(seqID: ImageSequence; mode: Integer; 
				opColor: RGBColor): OSErr;
FUNCTION SetDSequenceSrcRect
				(seqID: ImageSequence; srcRect: Rect): OSErr;
FUNCTION SetDSequenceMatrix
				(seqID: ImageSequence; 
				matrix: MatrixRecordPtr): OSErr;
FUNCTION SetDSequenceMask 	(seqID: ImageSequence; mask: RgnHandle): OSErr;
FUNCTION SetDSequenceMatte 	(seqID: ImageSequence; matte: PixMapHandle; 
				matteRect: Rect): OSErr;
FUNCTION SetDSequenceAccuracy 
				(seqID: ImageSequence; 
				accuracy: CodecQ): OSErr;
FUNCTION SetDSequenceDataProc 
				(seqID: ImageSequence; 
				dataProc: DataProcRecordPtr; 
				bufferSize: LongInt): OSErr;
FUNCTION GetDSequenceImageBuffer 
				(seqID: ImageSequence; 
				VAR gworld: GWorldPtr): OSErr;
FUNCTION GetDSequenceScreenBuffer 
				(seqID: ImageSequence; 
				VAR gworld: GWorldPtr): OSErr;

Working With the StdPix Routine

FUNCTION StdPix			 (src: PixMapPtr; srcRect: Rect; 
				matrix: MatrixRecordPtr; mode: Integer; 
				mask: RgnHandle; matte: PixMapPtr; 
				matteRect: Rect; flags: Integer): OSErr
FUNCTION SetCompressedPixMapInfo 
				(pix: PixMapPtr; desc: ImageDescriptionHandle; data: Ptr; bufferSize: LongInt; 
				dataProc: DataProcRecordPtr; 
				progressProc: ProgressProcRecordPtr): OSErr;
FUNCTION GetCompressedPixMapInfo 
				(pix: PixMapPtr; 
				VAR desc: ImageDescriptionHandle; 
				VAR data: Ptr; VAR bufferSize: LongInt; 
				VAR dataProc: DataProcRecord; 
				VAR progressProc: ProgressProcRecord): OSErr;

Aligning Windows

PROCEDURE AlignWindow		(wp: WindowPtr; front: Boolean; 
				alignmentRect: RectPtr; 
				alignmentProc:AlignmentProcRecordPtr );
PROCEDURE DragAlignedWindow
				(wp: WindowPtr; startPt: Point; 
				VAR boundsRect: Rect; VAR alignmentRect: Rect; alignmentProc:AlignmentProcRecordPtr);
FUNCTION DragAlignedGrayRgn
				(theRgn: RgnHandle; startPt: Point; 
				VAR boundsRect: Rect; VAR slopRect: Rect; axis: Integer; actionProc: ProcPtr; 
				VAR alignmentRect: Rect; alignmentProc:AlignmentProcRecordPtr): LongInt;
PROCEDURE AlignScreenRect	(VAR rp: Rect; 
				alignmentProc:AlignmentProcRecordPtr);

Working With Graphics Devices and Graphics Worlds

FUNCTION GetBestDeviceRect	(VAR gdh: GDHandle; VAR rp: Rect): OSErr;
FUNCTION NewImageGWorld		(VAR gworld: GWorldPtr; 
				idh: ImageDescriptionHandle; 
				flags :GWorldFlags): OSErr;

Application-Defined Routines

Data-Loading Functions

FUNCTION MyDataLoadingProc 	(VAR dataP: Ptr; bytesNeeded: LongInt; 
				refcon: LongInt): OSErr;

Data-Unloading Functions

FUNCTION MyDataUnloadingProc
				(data: Ptr; bytesAdded: LongInt; 
				refcon: LongInt): OSErr;

Progress Functions

FUNCTION MyProgressProc		 (message: Integer; completeness: Fixed; 
				refcon: LongInt): OSErr;

Completion Functions

FUNCTION MyCompletionProc 	(result: OSErr; flag: Integer; 
				refcon: LongInt): OSErr;

Alignment Routines

PROCEDURE MyAlignmentProc	(rp: RectPtr, refcon: LongInt);

Result Codes

paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
codecErr	-8960	General error condition
noCodecErr	-8961	Image Compression Manager could not find the specified compressor
codecUnimpErr	-8962	Feature not implemented by this compressor
codecSizeErr	-8963	Invalid buffer size specified
codecScreenBufErr	-8964	Could not allocate the screen buffer
codecImageBufErr	-8965	Could not allocate the image buffer
codecSpoolErr	-8966	Error loading or unloading data
codecAbortErr	-8967	Operation aborted by the progress function
codecWouldOffScreenErr	-8968	Compressor would use screen buffer if it could
codecBadDataErr	-8969	Compressed data contains inconsistencies
codecDataVersErr	-8970	Compressor does not support the compression version used to compress the image
codecExtensionNotFoundErr	-8971	Requested extension is not in the image description
codecConditionErr	-8972	Component cannot perform requested operation
codecOpenErr	-8973	Could not open the compressor or decompressor